//
//  IMDeviceInfoService.h
//  DualMediationSDK
//
//  Created by YeJary on 2025/1/27.
//

#import <Foundation/Foundation.h>
#import "IMDeviceInfoModels.h"

@class UIViewController;

NS_ASSUME_NONNULL_BEGIN

/**
 * 设备信息服务
 * 
 * 功能说明：
 * - 获取GAID（Google Advertising ID）
 * - 获取国家地区代码（ISO 3166-1标准）
 * - 判断是否短屏设备（宽高比>0.5622）
 * - 提供设备屏幕信息
 * 
 * 使用注意：
 * - GAID获取需要在真机上测试
 * - 国家代码优先使用IP判断，备用Locale
 * - 短屏判断基于750*1334分辨率标准
 */
@interface IMDeviceInfoService : NSObject

/**
 * 获取共享实例
 * @return 服务实例
 */
+ (instancetype)sharedService;

#pragma mark - GAID相关

/**
 * 获取GAID（同步）
 * @return GAID字符串，获取失败返回nil
 */
- (nullable NSString *)getGAID;

/**
 * 获取GAID（异步）
 * @param completion 完成回调，result.data为NSString类型的GAID
 */
- (void)getGAIDWithCompletion:(IMDeviceInfoCompletionBlock)completion;

/**
 * 检查GAID是否可用
 * @return YES表示可用，NO表示不可用
 */
- (BOOL)isGAIDAvailable;

#pragma mark - 国家代码相关

/**
 * 获取国家代码（同步）
 * @return 国家代码（ISO 3166-1标准两字母代码），获取失败返回nil
 */
- (nullable NSString *)getCountryCode;

/**
 * 获取国家信息（同步）
 * @return 国家信息对象
 */
- (IMCountryInfo *)getCountryInfo;

/**
 * 获取国家信息（异步）
 * @param completion 完成回调，result.data为IMCountryInfo类型
 */
- (void)getCountryInfoWithCompletion:(IMDeviceInfoCompletionBlock)completion;

/**
 * 通过IP获取国家代码（异步）
 * @param completion 完成回调
 */
- (void)getCountryCodeByIPWithCompletion:(IMDeviceInfoCompletionBlock)completion;

#pragma mark - 屏幕设备相关

/**
 * 判断是否短屏设备（基于当前屏幕）
 * @return YES表示短屏设备，NO表示长屏设备
 */
- (BOOL)isShortDevice;

/**
 * 判断是否短屏设备（基于指定Activity上下文）
 * @param viewController 视图控制器上下文
 * @return YES表示短屏设备，NO表示长屏设备
 */
- (BOOL)isShortDeviceForViewController:(UIViewController *)viewController;

/**
 * 获取设备屏幕信息
 * @return 屏幕信息对象
 */
- (IMDeviceScreenInfo *)getScreenInfo;

/**
 * 获取指定视图控制器的屏幕信息
 * @param viewController 视图控制器
 * @return 屏幕信息对象
 */
- (IMDeviceScreenInfo *)getScreenInfoForViewController:(UIViewController *)viewController;

#pragma mark - 设备标识相关

/**
 * 获取IDFA（iOS广告标识符）
 * @return IDFA字符串，获取失败或用户拒绝返回nil
 */
- (nullable NSString *)getIDFA;

/**
 * 获取IDFV（iOS供应商标识符）
 * @return IDFV字符串
 */
- (nullable NSString *)getIDFV;

/**
 * 获取设备型号
 * @return 设备型号字符串
 */
- (NSString *)getDeviceModel;

/**
 * 获取系统版本
 * @return 系统版本字符串
 */
- (NSString *)getSystemVersion;

#pragma mark - 综合设备信息

/**
 * 获取设备基本信息
 * @return 包含设备基本信息的字典
 */
- (NSDictionary *)getDeviceInfo;

/**
 * 获取设备详细信息
 * @return 包含设备详细信息的字典
 */
- (NSDictionary *)getDetailedDeviceInfo;

/**
 * 获取网络信息
 * @return 包含网络信息的字典
 */
- (NSDictionary *)getNetworkInfo;

@end

NS_ASSUME_NONNULL_END